home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / lib / mozilla-firefox / include / gfx / nsIRenderingContext.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-05-08  |  39.4 KB  |  1,094 lines
  1. /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Mozilla Public License Version
  6.  * 1.1 (the "License"); you may not use this file except in compliance with
  7.  * the License. You may obtain a copy of the License at
  8.  * http://www.mozilla.org/MPL/
  9.  *
  10.  * Software distributed under the License is distributed on an "AS IS" basis,
  11.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12.  * for the specific language governing rights and limitations under the
  13.  * License.
  14.  *
  15.  * The Original Code is mozilla.org code.
  16.  *
  17.  * The Initial Developer of the Original Code is
  18.  * Netscape Communications Corporation.
  19.  * Portions created by the Initial Developer are Copyright (C) 1998
  20.  * the Initial Developer. All Rights Reserved.
  21.  *
  22.  * Contributor(s):
  23.  *   Roland Mainz <roland.mainz@informatik.med.uni-giessen.de>
  24.  *   Leon Sha <leon.sha@sun.com>
  25.  *   Boris Zbarsky <bzbarsky@mit.edu>
  26.  *
  27.  * Alternatively, the contents of this file may be used under the terms of
  28.  * either of the GNU General Public License Version 2 or later (the "GPL"),
  29.  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  30.  * in which case the provisions of the GPL or the LGPL are applicable instead
  31.  * of those above. If you wish to allow use of your version of this file only
  32.  * under the terms of either the GPL or the LGPL, and not to allow others to
  33.  * use your version of this file under the terms of the MPL, indicate your
  34.  * decision by deleting the provisions above and replace them with the notice
  35.  * and other provisions required by the GPL or the LGPL. If you do not delete
  36.  * the provisions above, a recipient may use your version of this file under
  37.  * the terms of any one of the MPL, the GPL or the LGPL.
  38.  *
  39.  * ***** END LICENSE BLOCK ***** */
  40.  
  41. #ifndef nsIRenderingContext_h___
  42. #define nsIRenderingContext_h___
  43.  
  44. #include "nscore.h"
  45. #include "nsISupports.h"
  46. #include "nsColor.h"
  47. #include "nsCoord.h"
  48. #include "nsIDrawingSurface.h"
  49. #include <stdio.h>
  50.  
  51. class nsIWidget;
  52. class nsIFontMetrics;
  53. class nsTransform2D;
  54. class nsString;
  55. class nsIDeviceContext;
  56. class nsIRegion;
  57. class nsIAtom;
  58.  
  59. struct nsFont;
  60. struct nsPoint;
  61. struct nsRect;
  62. struct nsTextDimensions;
  63. #ifdef MOZ_MATHML
  64. struct nsBoundingMetrics;
  65. #endif
  66.  
  67. /* gfx2 */
  68. class imgIContainer;
  69.  
  70. //cliprect/region combination methods
  71.  
  72. typedef enum
  73. {
  74.   nsClipCombine_kIntersect = 0,
  75.   nsClipCombine_kUnion = 1,
  76.   nsClipCombine_kSubtract = 2,
  77.   nsClipCombine_kReplace = 3
  78. } nsClipCombine;
  79.  
  80. //linestyles
  81. typedef enum
  82. {
  83.   nsLineStyle_kNone   = 0,
  84.   nsLineStyle_kSolid  = 1,
  85.   nsLineStyle_kDashed = 2,
  86.   nsLineStyle_kDotted = 3
  87. } nsLineStyle;
  88.  
  89. typedef enum
  90. {
  91.   nsPenMode_kNone   = 0,
  92.   nsPenMode_kInvert = 1
  93. } nsPenMode;
  94.  
  95.  
  96. // IID for the nsIRenderingContext interface
  97. #define NS_IRENDERING_CONTEXT_IID \
  98.  { 0xd91f728b, 0xd7f4, 0x4e19,{0x8b, 0xdd, 0x98, 0x99, 0x3f, 0xdf, 0xec, 0xc6}}
  99.  
  100. //----------------------------------------------------------------------
  101.  
  102. // RenderingContext interface
  103. class nsIRenderingContext : public nsISupports
  104. {
  105. public:
  106.   NS_DEFINE_STATIC_IID_ACCESSOR(NS_IRENDERING_CONTEXT_IID)
  107.  
  108.   //TBD: bind/unbind, transformation of scalars (hacky), 
  109.   //potential drawmode for selection, polygons. MMP
  110.  
  111.   /**
  112.    * Initialize the RenderingContext
  113.    * @param aContext the device context to use.
  114.    * @param aWidget the widget to hook up to
  115.    * @result The result of the initialization, NS_Ok if no errors
  116.    */
  117.   NS_IMETHOD Init(nsIDeviceContext* aContext, nsIWidget *aWidget) = 0;
  118.  
  119.   /**
  120.    * Initialize the RenderingContext
  121.    * @param aContext the device context to use for the drawing.
  122.    * @param aSurface the surface to draw into
  123.    * @result The result of the initialization, NS_Ok if no errors
  124.    */
  125.   NS_IMETHOD Init(nsIDeviceContext* aContext, nsIDrawingSurface* aSurface) = 0;
  126.  
  127.   /**
  128.    * Reset the rendering context
  129.    */
  130.   NS_IMETHOD Reset(void) = 0;
  131.  
  132.   /**
  133.    * Get the DeviceContext that this RenderingContext was initialized with
  134.    * @result the device context
  135.    */
  136.   NS_IMETHOD GetDeviceContext(nsIDeviceContext *& aDeviceContext) = 0;
  137.  
  138.   /**
  139.    * Lock a rect of the drawing surface associated with the
  140.    * rendering context. do not attempt to use any of the Rendering Context
  141.    * rendering or state management methods until the drawing surface has
  142.    * been Unlock()ed. if a drawing surface is Lock()ed with this method,
  143.    * it must be Unlock()ed by calling UnlockDrawingSurface() rather than
  144.    * just calling the Unlock() method on the drawing surface directly.
  145.    * see nsIDrawingSurface.h for more information
  146.    * @return error status
  147.    **/
  148.   NS_IMETHOD LockDrawingSurface(PRInt32 aX, PRInt32 aY, PRUint32 aWidth, PRUint32 aHeight,
  149.                                 void **aBits, PRInt32 *aStride, PRInt32 *aWidthBytes,
  150.                                 PRUint32 aFlags) = 0;
  151.  
  152.   /**
  153.    * Unlock a rect of the drawing surface associated with the rendering
  154.    * context. see nsIDrawingSurface.h for more information.
  155.    * @return error status
  156.    **/
  157.   NS_IMETHOD UnlockDrawingSurface(void) = 0;
  158.  
  159.   /**
  160.    * Selects an offscreen drawing surface into the RenderingContext to draw to.
  161.    * @param aSurface is the offscreen surface we are going to draw to.
  162.    *        if nsnull, the original drawing surface obtained at initialization
  163.    *        should be selected.
  164.    */
  165.   NS_IMETHOD SelectOffScreenDrawingSurface(nsIDrawingSurface* aSurface) = 0;
  166.  
  167.   /**
  168.    * Get the currently selected drawing surface
  169.    * @param aSurface out parameter for the current drawing surface
  170.    */
  171.   NS_IMETHOD GetDrawingSurface(nsIDrawingSurface* *aSurface) = 0;
  172.  
  173.   /**
  174.    * Returns in aResult any rendering hints that the context has.
  175.    * See below for the hints bits. Always returns NS_OK.
  176.    */
  177.   NS_IMETHOD GetHints(PRUint32& aResult) = 0;
  178.  
  179.   /**
  180.    * Save a graphical state onto a stack.
  181.    */
  182.   NS_IMETHOD PushState(void) = 0;
  183.  
  184.   /**
  185.    * Get and and set RenderingContext to this graphical state
  186.    */
  187.   NS_IMETHOD PopState(void) = 0;
  188.  
  189.   /**
  190.    * Tells if a given rectangle is visible within the rendering context
  191.    * @param aRect is the rectangle that will be checked for visiblity
  192.    * @result If true, that rectanglular area is visable.
  193.    */
  194.   NS_IMETHOD IsVisibleRect(const nsRect& aRect, PRBool &aIsVisible) = 0;
  195.  
  196.   /**
  197.    * Sets the clipping for the RenderingContext to the passed in rectangle.
  198.    * The rectangle is in app units!
  199.    * @param aRect The rectangle to set the clipping rectangle to
  200.    * @param aCombine how to combine this rect with the current clip region.
  201.    *        see the bottom of nsIRenderingContext.h
  202.    */
  203.   NS_IMETHOD SetClipRect(const nsRect& aRect, nsClipCombine aCombine) = 0;
  204.  
  205.   /**
  206.    * Gets the bounds of the clip region of the RenderingContext. The bounds are returned
  207.    * in device units!
  208.    * @param aRect out parameter to contain the clip region bounds
  209.    *        for the RenderingContext
  210.    * @return PR_TRUE if the rendering context has a local cliprect set
  211.    *         else aRect is undefined
  212.    */
  213.   NS_IMETHOD GetClipRect(nsRect &aRect, PRBool &aHasLocalClip) = 0;
  214.  
  215.   /**
  216.    * Sets the line style for the RenderingContext 
  217.    * @param aLineStyle The line style
  218.    * @return NS_OK if the line style is correctly set
  219.    */
  220.   NS_IMETHOD SetLineStyle(nsLineStyle aLineStyle) = 0;
  221.  
  222.   /**
  223.    * Gets the line style for the RenderingContext
  224.    * @param aLineStyle The line style to be retrieved
  225.    * @return NS_OK if the line style is correctly retrieved
  226.    */
  227.   NS_IMETHOD GetLineStyle(nsLineStyle &aLineStyle) = 0;
  228.  
  229.   /**
  230.    * Gets the Pen Mode for the RenderingContext
  231.    * @param aPenMode The Pen Mode to be retrieved
  232.    * @return NS_OK if the Pen Mode is correctly retrieved
  233.    */
  234.   NS_IMETHOD GetPenMode(nsPenMode &aPenMode) =0;
  235.  
  236.   /**
  237.    * Sets the Pen Mode for the RenderingContext 
  238.    * @param aPenMode The Pen Mode
  239.    * @return NS_OK if the Pen Mode is correctly set
  240.    */
  241.   NS_IMETHOD SetPenMode(nsPenMode aPenMode) =0;
  242.  
  243.  
  244.   /**
  245.    * Sets the clipping for the RenderingContext to the passed in region.
  246.    * The region is in device coordinates!
  247.    * @param aRegion The region to set the clipping area to, IN DEVICE COORDINATES
  248.    * @param aCombine how to combine this region with the current clip region.
  249.    *        see the bottom of nsIRenderingContext.h
  250.    */
  251.   NS_IMETHOD SetClipRegion(const nsIRegion& aRegion, nsClipCombine aCombine) = 0;
  252.  
  253.   /**
  254.    * Gets a copy of the current clipping region for the RenderingContext
  255.    * The region is in device coordinates!
  256.    * @param aRegion inout parameter representing the clip region.
  257.    *        if SetClipRegion() is called, do not assume that GetClipRegion()
  258.    *        will return the same object.
  259.    */
  260.   NS_IMETHOD CopyClipRegion(nsIRegion &aRegion) = 0;
  261.  
  262.   /**
  263.    * Gets the current clipping region for the RenderingContext
  264.    * The region is in device coordinates!
  265.    * @param aRegion out parameter representing the clip region.
  266.    *        if SetClipRegion() is called, do not assume that GetClipRegion()
  267.    *        will return the same object.
  268.    */
  269.   NS_IMETHOD GetClipRegion(nsIRegion **aRegion) = 0;
  270.  
  271.   /**
  272.    * Sets the forground color for the RenderingContext
  273.    * @param aColor The color to set the RenderingContext to
  274.    */
  275.   NS_IMETHOD SetColor(nscolor aColor) = 0;
  276.  
  277.   /**
  278.    * Get the forground color for the RenderingContext
  279.    * @return The current forground color of the RenderingContext
  280.    */
  281.   NS_IMETHOD GetColor(nscolor &aColor) const = 0;
  282.  
  283.   /**
  284.    * Sets the font for the RenderingContext
  285.    * @param aFont The font to use in the RenderingContext
  286.    */
  287.   NS_IMETHOD SetFont(const nsFont& aFont, nsIAtom* aLangGroup) = 0;
  288.  
  289.   /**
  290.    * Sets the font for the RenderingContext
  291.    * @param aFontMetric The font metrics representing the
  292.    *        font to use in the RenderingContext
  293.    */
  294.   NS_IMETHOD SetFont(nsIFontMetrics *aFontMetrics) = 0;
  295.  
  296.   /**
  297.    * Get the current fontmetrics for the RenderingContext
  298.    * @return The current font of the RenderingContext
  299.    */
  300.   NS_IMETHOD GetFontMetrics(nsIFontMetrics *&aFontMetrics) = 0;
  301.  
  302.   /**
  303.    *  Add in a translate to the RenderingContext's transformation matrix
  304.    * @param aX The horizontal translation
  305.    * @param aY The vertical translation
  306.    */
  307.   NS_IMETHOD Translate(nscoord aX, nscoord aY) = 0;
  308.  
  309.   /**
  310.    *  Add in a scale to the RenderingContext's transformation matrix
  311.    * @param aX The horizontal scale
  312.    * @param aY The vertical scale
  313.    */
  314.   NS_IMETHOD Scale(float aSx, float aSy) = 0;
  315.  
  316.   struct PushedTranslation {
  317.     float mSavedX, mSavedY;
  318.   };
  319.  
  320.   class AutoPushTranslation {
  321.     nsIRenderingContext* mCtx;
  322.     PushedTranslation mPushed;
  323.   public:
  324.     AutoPushTranslation(nsIRenderingContext* aCtx, nscoord aX, nscoord aY)
  325.       : mCtx(aCtx) {
  326.       mCtx->PushTranslation(&mPushed);
  327.       mCtx->Translate(aX, aY);
  328.     }
  329.     ~AutoPushTranslation() {
  330.       mCtx->PopTranslation(&mPushed);
  331.     }
  332.   };
  333.  
  334.   NS_IMETHOD PushTranslation(PushedTranslation* aState) = 0;
  335.  
  336.   NS_IMETHOD PopTranslation(PushedTranslation* aState) = 0;
  337.  
  338.   /** 
  339.    * Get the current transformation matrix for the RenderingContext
  340.    * @return The transformation matrix for the RenderingContext
  341.    */
  342.   NS_IMETHOD GetCurrentTransform(nsTransform2D *&aTransform) = 0;
  343.  
  344.   /**
  345.    * Create an offscreen drawing surface compatible with this RenderingContext.
  346.    * The rect passed in is not affected by any transforms in the rendering
  347.    * context and the values are in device units.
  348.    * @param aBounds A rectangle representing the size for the drawing surface.
  349.    *                if nsnull then a bitmap will not be created and associated
  350.    *                with the new drawing surface
  351.    * @param aSurfFlags see bottom of nsIRenderingContext.h
  352.    * @return A nsIDrawingSurface*
  353.    */
  354.   NS_IMETHOD CreateDrawingSurface(const nsRect& aBounds, PRUint32 aSurfFlags, nsIDrawingSurface* &aSurface) = 0;
  355.  
  356.   /**
  357.    * Destroy a drawing surface created by CreateDrawingSurface()
  358.    * @param aDS A drawing surface to destroy
  359.    */
  360.   NS_IMETHOD DestroyDrawingSurface(nsIDrawingSurface* aDS) = 0;
  361.  
  362.   /**
  363.    * Draw a line
  364.    * @param aXO starting horiztonal coord in twips
  365.    * @param aY0 starting vertical coord in twips
  366.    * @param aX1 end horiztonal coord in twips
  367.    * @param aY1 end vertical coord in twips
  368.    */
  369.   NS_IMETHOD DrawLine(nscoord aX0, nscoord aY0, nscoord aX1, nscoord aY1) = 0;
  370.  
  371.   /**
  372.    * Draw a polyline
  373.    * @param aPoints array of endpoints
  374.    * @param aNumPonts number of points
  375.    */
  376.   NS_IMETHOD DrawPolyline(const nsPoint aPoints[], PRInt32 aNumPoints) = 0;
  377.  
  378.   /**
  379.    * Draw a rectangle
  380.    * @param aRect The rectangle to draw
  381.    */
  382.   NS_IMETHOD DrawRect(const nsRect& aRect) = 0;
  383.  
  384.   /**
  385.    * Draw a rectangle
  386.    * @param aX Horizontal left Coordinate in twips
  387.    * @param aY Vertical top Coordinate in twips
  388.    * @param aWidth Width of rectangle in twips
  389.    * @param aHeight Height of rectangle in twips
  390.    */
  391.   NS_IMETHOD DrawRect(nscoord aX, nscoord aY, nscoord aWidth, nscoord aHeight) = 0;
  392.  
  393.   /**
  394.    * Fill a rectangle in the current foreground color
  395.    * @param aRect The rectangle to draw
  396.    */
  397.   NS_IMETHOD FillRect(const nsRect& aRect) = 0;
  398.  
  399.   /**
  400.    * Fill a rectangle in the current foreground color
  401.    * @param aX Horizontal left Coordinate in twips
  402.    * @param aY Vertical top Coordinate in twips
  403.    * @param aWidth Width of rectangle in twips
  404.    * @param aHeight Height of rectangle in twips
  405.    */
  406.   NS_IMETHOD FillRect(nscoord aX, nscoord aY, nscoord aWidth, nscoord aHeight) = 0;
  407.  
  408.   /**
  409.    * XOR Invert a rectangle in the current foreground color
  410.    * @param aRect The rectangle to draw
  411.    */
  412.   NS_IMETHOD InvertRect(const nsRect& aRect) = 0;
  413.  
  414.   /**
  415.    * XOR Invert a rectangle in the current foreground color
  416.    * @param aX Horizontal left Coordinate in twips
  417.    * @param aY Vertical top Coordinate in twips
  418.    * @param aWidth Width of rectangle in twips
  419.    * @param aHeight Height of rectangle in twips
  420.    */
  421.   NS_IMETHOD InvertRect(nscoord aX, nscoord aY, nscoord aWidth, nscoord aHeight) = 0;
  422.  
  423.   /**
  424.    * For platforms (e.g., Cocoa) that implicitly double buffer, this call can be used
  425.    * to force a buffer flush following the painting of a rectangle.  This
  426.    * call needs to be used any time drawing of rects is being done "on the fly",
  427.    * outside of the normal painting process.
  428.    * Examples include the blinking caret and tabbing through subimages in an
  429.    * image map.
  430.    */
  431.   NS_IMETHOD FlushRect(const nsRect& aRect) = 0;
  432.   NS_IMETHOD FlushRect(nscoord aX, nscoord aY, nscoord aWidth, nscoord aHeight) = 0;
  433.   
  434.   /**
  435.    * Draw a poly in the current foreground color
  436.    * @param aPoints points to use for the drawing, last must equal first
  437.    * @param aNumPonts number of points in the polygon
  438.    */
  439.   NS_IMETHOD DrawPolygon(const nsPoint aPoints[], PRInt32 aNumPoints) = 0;
  440.  
  441.   /**
  442.    * Fill a poly in the current foreground color
  443.    * @param aPoints points to use for the drawing, last must equal first
  444.    * @param aNumPonts number of points in the polygon
  445.    */
  446.   NS_IMETHOD FillPolygon(const nsPoint aPoints[], PRInt32 aNumPoints) = 0;
  447.  
  448.   /**
  449.    * Draw an ellipse in the current foreground color
  450.    * @param aRect The rectangle define bounds of ellipse to draw
  451.    */
  452.   NS_IMETHOD DrawEllipse(const nsRect& aRect) = 0;
  453.  
  454.   /**
  455.    * Draw an ellipse in the current foreground color
  456.    * @param aX Horizontal left Coordinate in twips
  457.    * @param aY Vertical top Coordinate in twips
  458.    * @param aWidth Width of horizontal axis in twips
  459.    * @param aHeight Height of vertical axis in twips
  460.    */
  461.   NS_IMETHOD DrawEllipse(nscoord aX, nscoord aY, nscoord aWidth, nscoord aHeight) = 0;
  462.  
  463.   /**
  464.    * Fill an ellipse in the current foreground color
  465.    * @param aRect The rectangle define bounds of ellipse to draw
  466.    */
  467.   NS_IMETHOD FillEllipse(const nsRect& aRect) = 0;
  468.  
  469.   /**
  470.    * Fill an ellipse in the current foreground color
  471.    * @param aX Horizontal left Coordinate in twips
  472.    * @param aY Vertical top Coordinate in twips
  473.    * @param aWidth Width of horizontal axis in twips
  474.    * @param aHeight Height of vertical axis in twips
  475.    */
  476.   NS_IMETHOD FillEllipse(nscoord aX, nscoord aY, nscoord aWidth, nscoord aHeight) = 0;
  477.  
  478.   /**
  479.    * Draw an arc in the current forground color
  480.    * @param aRect The rectangle define bounds of ellipse to use
  481.    * @param aStartAngle the starting angle of the arc, in degrees
  482.    * @param aEndAngle The ending angle of the arc, in degrees
  483.    */
  484.   NS_IMETHOD DrawArc(const nsRect& aRect,
  485.                      float aStartAngle, float aEndAngle) = 0;
  486.  
  487.   /**
  488.    * Draw an arc in the current forground color
  489.    * @param aX Horizontal left Coordinate in twips
  490.    * @param aY Vertical top Coordinate in twips
  491.    * @param aWidth Width of horizontal axis in twips
  492.    * @param aHeight Height of vertical axis in twips
  493.    * @param aStartAngle the starting angle of the arc, in degrees
  494.    * @param aEndAngle The ending angle of the arc, in degrees
  495.    */
  496.   NS_IMETHOD DrawArc(nscoord aX, nscoord aY, nscoord aWidth, nscoord aHeight,
  497.                      float aStartAngle, float aEndAngle) = 0;
  498.  
  499.   /**
  500.    * Fill an arc in the current forground color
  501.    * @param aRect The rectangle define bounds of ellipse to use
  502.    * @param aStartAngle the starting angle of the arc, in degrees
  503.    * @param aEndAngle The ending angle of the arc, in degrees
  504.    */
  505.   NS_IMETHOD FillArc(const nsRect& aRect,
  506.                      float aStartAngle, float aEndAngle) = 0;
  507.  
  508.   /**
  509.    * Fill an arc in the current forground color
  510.    * @param aX Horizontal left Coordinate in twips
  511.    * @param aY Vertical top Coordinate in twips
  512.    * @param aWidth Width of horizontal axis in twips
  513.    * @param aHeight Height of vertical axis in twips
  514.    * @param aStartAngle the starting angle of the arc, in degrees
  515.    * @param aEndAngle The ending angle of the arc, in degrees
  516.    */
  517.   NS_IMETHOD FillArc(nscoord aX, nscoord aY, nscoord aWidth, nscoord aHeight,
  518.                      float aStartAngle, float aEndAngle) = 0;
  519.  
  520.   /**
  521.    * Returns the width (in app units) of an 8-bit character
  522.    * If no font has been Set, the results are undefined.
  523.    * @param aC character to measure
  524.    * @param aWidth out parameter for width
  525.    * @return error status
  526.    */
  527.   NS_IMETHOD GetWidth(char aC, nscoord &aWidth) = 0;
  528.  
  529.   /**
  530.    * Returns the width (in app units) of a unicode character
  531.    * If no font has been Set, the results are undefined.
  532.    * @param aC character to measure
  533.    * @param aWidth out parameter for width
  534.    * @param aFontID an optional out parameter used to store a
  535.    *        font identifier that can be passed into the DrawString()
  536.    *        methods to speed rendering
  537.    * @return error status
  538.    */
  539.   NS_IMETHOD GetWidth(PRUnichar aC, nscoord &aWidth,
  540.                       PRInt32 *aFontID = nsnull) = 0;
  541.  
  542.   /**
  543.    * Returns the width (in app units) of an nsString
  544.    * If no font has been Set, the results are undefined.
  545.    * @param aString string to measure
  546.    * @param aWidth out parameter for width
  547.    * @param aFontID an optional out parameter used to store a
  548.    *        font identifier that can be passed into the DrawString()
  549.    *        methods to speed rendering
  550.    * @return error status
  551.    */
  552.   NS_IMETHOD GetWidth(const nsString& aString, nscoord &aWidth,
  553.                       PRInt32 *aFontID = nsnull) = 0;
  554.  
  555.   /**
  556.    * Returns the width (in app units) of an 8-bit character string
  557.    * If no font has been Set, the results are undefined.
  558.    * @param aString string to measure
  559.    * @param aWidth out parameter for width
  560.    * @return error status
  561.    */
  562.   NS_IMETHOD GetWidth(const char* aString, nscoord& aWidth) = 0;
  563.  
  564.   /**
  565.    * Returns the width (in app units) of an 8-bit character string
  566.    * If no font has been Set, the results are undefined.
  567.    * @param aString string to measure
  568.    * @param aLength number of characters in string
  569.    * @param aWidth out parameter for width
  570.    * @return error status
  571.    */
  572.   NS_IMETHOD GetWidth(const char* aString, PRUint32 aLength,
  573.                       nscoord& aWidth) = 0;
  574.  
  575.   /**
  576.    * Returns the width (in app units) of a Unicode character string
  577.    * If no font has been Set, the results are undefined.
  578.    * @param aString string to measure
  579.    * @param aLength number of characters in string
  580.    * @param aWidth out parameter for width
  581.    * @param aFontID an optional out parameter used to store a
  582.    *        font identifier that can be passed into the DrawString()
  583.    *        methods to speed rendering
  584.    * @return error status
  585.    */
  586.   NS_IMETHOD GetWidth(const PRUnichar *aString, PRUint32 aLength,
  587.                       nscoord &aWidth, PRInt32 *aFontID = nsnull) = 0;
  588.  
  589.   /**
  590.    * Returns the dimensions of a string, i.e., the overall extent of a string
  591.    * whose rendering may involve switching between different fonts that have
  592.    * different metrics.
  593.    * @param aString string to measure
  594.    * @param aLength number of characters in string
  595.    * @param aFontID an optional out parameter used to store a
  596.    *        font identifier that can be passed into the DrawString()
  597.    *        methods to speed measurements
  598.    * @return aDimensions struct that contains the extent of the string (see below)
  599.    */
  600.   NS_IMETHOD GetTextDimensions(const char* aString, PRUint32 aLength,
  601.                                nsTextDimensions& aDimensions) = 0;
  602.   NS_IMETHOD GetTextDimensions(const PRUnichar* aString, PRUint32 aLength,
  603.                                nsTextDimensions& aDimensions, PRInt32* aFontID = nsnull) = 0;
  604.  
  605. #if defined(_WIN32) || defined(XP_OS2) || defined(MOZ_X11) || defined(XP_BEOS)
  606.   /**
  607.    * Given an available width and an array of break points,
  608.    * returns the dimensions (in app units) of the text that fit and
  609.    * the number of characters that fit. The number of characters
  610.    * corresponds to an entry in the break array.
  611.    * If no font has been set, the results are undefined.
  612.    * @param aString, string to measure
  613.    * @param aLength, number of characters in string
  614.    * @param aAvailWidth, the available space in which the text must fit
  615.    * @param aBreaks, array of places to break. Specified as offsets from the
  616.    *          start of the string
  617.    * @param aNumBreaks, the number of entries in the break array. The last
  618.    *          entry in the break array must equal the length of the string
  619.    * @param aDimensions, out parameter for the dimensions, the ascent and descent
  620.    *           of the last word are left out to allow possible line-breaking before
  621.    *           the last word. However, the width of the last word is included.
  622.    * @param aNumCharsFit, the number of characters that fit in the available space
  623.    * @param aLastWordDimensions, dimensions of the last word, the width field,
  624.    *             dimensions.width, should be -1 for an unknown width. But the 
  625.    *             ascent and descent are expected to be known.
  626.    * @param aFontID, an optional out parameter used to store a
  627.    *        font identifier that can be passed into the DrawString()
  628.    *        methods to speed rendering
  629.    * @return error status
  630.    */
  631.   NS_IMETHOD GetTextDimensions(const char*       aString,
  632.                                PRInt32           aLength,
  633.                                PRInt32           aAvailWidth,
  634.                                PRInt32*          aBreaks,
  635.                                PRInt32           aNumBreaks,
  636.                                nsTextDimensions& aDimensions,
  637.                                PRInt32&          aNumCharsFit,
  638.                                nsTextDimensions& aLastWordDimensions,
  639.                                PRInt32*          aFontID = nsnull) = 0;
  640.  
  641.   NS_IMETHOD GetTextDimensions(const PRUnichar*  aString,
  642.                                PRInt32           aLength,
  643.                                PRInt32           aAvailWidth,
  644.                                PRInt32*          aBreaks,
  645.                                PRInt32           aNumBreaks,
  646.                                nsTextDimensions& aDimensions,
  647.                                PRInt32&          aNumCharsFit,
  648.                                nsTextDimensions& aLastWordDimensions,
  649.                                PRInt32*          aFontID = nsnull) = 0;
  650. #endif
  651.  
  652.   /**
  653.    * Draw a string in the RenderingContext
  654.    * @param aString The string to draw
  655.    * @param aLength The length of the aString
  656.    * @param aX Horizontal starting point of baseline
  657.    * @param aY Vertical starting point of baseline.
  658.    * @param aSpacing inter-character spacing to apply
  659.    */
  660.   NS_IMETHOD DrawString(const char *aString, PRUint32 aLength,
  661.                         nscoord aX, nscoord aY,
  662.                         const nscoord* aSpacing = nsnull) = 0;
  663.  
  664.   /**
  665.    * Draw a string in the RenderingContext
  666.    * @param aString A PRUnichar of the string
  667.    * @param aLength The length of the aString
  668.    * @param aX Horizontal starting point of baseline
  669.    * @param aY Vertical starting point of baseline.
  670.    * @param aFontID an optional parameter used to speed font
  671.    *        selection for complex unicode strings. the value
  672.    *        passed is returned by the DrawString() methods.
  673.    * @param aSpacing inter-character spacing to apply
  674.    */
  675.   NS_IMETHOD DrawString(const PRUnichar *aString, PRUint32 aLength,
  676.                         nscoord aX, nscoord aY,
  677.                         PRInt32 aFontID = -1,
  678.                         const nscoord* aSpacing = nsnull) = 0;
  679.  
  680.   /**
  681.    * Draw a string in the RenderingContext
  682.    * @param aString A nsString of the string
  683.    * @param aX Horizontal starting point of baseline
  684.    * @param aY Vertical starting point of baseline.
  685.    * @param aFontID an optional parameter used to speed font
  686.    *        selection for complex unicode strings. the value
  687.    *        passed is returned by the DrawString() methods.
  688.    * @param aSpacing inter-character spacing to apply
  689.    */
  690.   NS_IMETHOD DrawString(const nsString& aString, nscoord aX, nscoord aY,
  691.                         PRInt32 aFontID = -1,
  692.                         const nscoord* aSpacing = nsnull) = 0;
  693.  
  694.   /**
  695.    * Copy offscreen pixelmap to this RenderingContext.
  696.    * @param aSrcSurf drawing surface to copy bits from
  697.    * @param aSrcX x offset into source pixelmap to copy from
  698.    * @param aSrcY y offset into source pixelmap to copy from
  699.    * @param aDestBounds Destination rectangle to copy to
  700.    * @param aCopyFlags see below
  701.    */
  702.   NS_IMETHOD CopyOffScreenBits(nsIDrawingSurface* aSrcSurf, PRInt32 aSrcX, PRInt32 aSrcY,
  703.                                const nsRect &aDestBounds, PRUint32 aCopyFlags) = 0;
  704.   //~~~
  705.   NS_IMETHOD RetrieveCurrentNativeGraphicData(PRUint32 * ngd) = 0;
  706.  
  707.  
  708.   /**
  709.    * Get a drawing surface used as a backbuffer.
  710.    * Depending on the platform this will either cause a backbuffer surface to be allocated
  711.    * or an existing cached backbuffer will be returned. If the backbuffer is being cached
  712.    * asking for aMaxSize which is different from a previous request may cause the platform
  713.    * to dump it's cached backbuffer and reallocate a backbuffer of a size which will allow aMaxSize 
  714.    * buffer to be allocated.
  715.    *
  716.    * @param aRequestedSize size of the backbuffer area requested
  717.    * @param aMaxSize maximum size that may be requested for the backbuffer
  718.    * @param aForBlending parameter telling if the buffer will be used for blending
  719.    * @param aBackbuffer drawing surface used as the backbuffer
  720.    */
  721.   NS_IMETHOD GetBackbuffer(const nsRect &aRequestedSize, const nsRect &aMaxSize, PRBool aForBlending, nsIDrawingSurface* &aBackbuffer) = 0;
  722.  
  723.   /**
  724.    * Release a drawing surface used as the backbuffer
  725.    * If the platform caches the backbuffer this call will destroy it.
  726.    */
  727.   NS_IMETHOD ReleaseBackbuffer(void) = 0;
  728.  
  729.   /**
  730.    * Destroy the drawing surface used as the backbuffer. If the platform
  731.    * does not maintain a cached backbuffer this call will do nothing.
  732.    */
  733.   NS_IMETHOD DestroyCachedBackbuffer(void) = 0;
  734.  
  735.   /**
  736.    * Some platforms may not want a backbuffer at all. Returning false
  737.    * here allows them to achieve that
  738.    *
  739.    * @param aUseBackbuffer PR_TRUE if we should use a backbuffer, PR_FALSE if not
  740.    */
  741.   NS_IMETHOD UseBackbuffer(PRBool* aUseBackbuffer) = 0;
  742.  
  743.  
  744. #ifdef MOZ_MATHML
  745.   /**
  746.    * Returns bounding metrics (in app units) of an 8-bit character string
  747.    * @param aString string to measure
  748.    * @param aLength number of characters in string
  749.    * @return aBoundingMetrics struct that contains various metrics (see below)
  750.    * @return error status
  751.    */
  752.   NS_IMETHOD
  753.   GetBoundingMetrics(const char*        aString,
  754.                      PRUint32           aLength,
  755.                      nsBoundingMetrics& aBoundingMetrics) = 0;
  756.   /**
  757.    * Returns bounding metrics (in app units) of an Unicode character string
  758.    * @param aString string to measure
  759.    * @param aLength number of characters in string
  760.    * @param aFontID an optional out parameter used to store a
  761.    *        font identifier that can be passed into the GetBoundingMetrics()
  762.    *        methods to speed measurements
  763.    * @return aBoundingMetrics struct that contains various metrics (see below)
  764.    * @return error status
  765.    */
  766.   NS_IMETHOD
  767.   GetBoundingMetrics(const PRUnichar*   aString,
  768.                      PRUint32           aLength,
  769.                      nsBoundingMetrics& aBoundingMetrics,
  770.                      PRInt32*           aFontID = nsnull) = 0;
  771. #endif
  772.  
  773.  
  774.   /**
  775.    * Let the device context know whether we want text reordered with
  776.    * right-to-left base direction
  777.    */
  778.   NS_IMETHOD SetRightToLeftText(PRBool aIsRTL) = 0;
  779.  
  780.   /**
  781.    *  Draw a portion of an image, scaling it to fit within a specified rect.
  782.    *  @param aImage     The image to draw
  783.    *  @param aSrcRect   The rect (in twips) of the image to draw.
  784.    *                    [x,y] denotes the top left corner of the region.
  785.    *  @param aDestRect  The device context rect (in twips) that the image
  786.    *                    portion should occupy. [x,y] denotes the top left corner.
  787.    *                    [height,width] denotes the desired image size.
  788.    */
  789.   NS_IMETHOD DrawImage(imgIContainer *aImage, const nsRect & aSrcRect, const nsRect & aDestRect) = 0;
  790.  
  791.   /*
  792.    * Tiles an image over an area
  793.    * @param aImage       Image to tile
  794.    * @param aXImageStart x location where the origin (0,0) of the image starts
  795.    * @param aYImageStart y location where the origin (0,0) of the image starts
  796.    * @param aTargetRect  area to draw to
  797.    */
  798.   NS_IMETHOD DrawTile(imgIContainer *aImage,
  799.                       nscoord aXImageStart, nscoord aYImageStart,
  800.                       const nsRect * aTargetRect) = 0;
  801.  
  802.  
  803.   /**
  804.    * Get cluster details for a chunk of text.
  805.    *
  806.    * This will fill in the aClusterStarts array with information about
  807.    * what characters are the start of clusters for display.  The
  808.    * information is just a bitfield that is set to 1 if the character
  809.    * is the start of a cluster.  aClusterStarts must already be
  810.    * allocated to at least aLength items in length.  Array index zero
  811.    * being set to one indicates that the first character is the
  812.    * beginning of a cluster.
  813.    *
  814.    * @param aText Text on which to get details.
  815.    * @param aLength Length of the text.
  816.    * @param aClusterStarts Array of ints that will be populated
  817.    *        with information about which characters are the starts
  818.    *        of clusters.
  819.    *
  820.    */
  821.   NS_IMETHOD GetClusterInfo(const PRUnichar *aText,
  822.                             PRUint32 aLength,
  823.                             PRUint8 *aClusterStarts) = 0;
  824.  
  825.   /**
  826.    * Find the closest cursor position for a given x coordinate.
  827.    *
  828.    * This will find the closest byte index for a given x coordinate.
  829.    * This takes into account grapheme clusters and bidi text.
  830.    *
  831.    * @param aText Text on which to operate.
  832.    * @param aLength Length of the text.
  833.    * @param aPt the x/y position in the string to check.
  834.    *
  835.    * @return Index where the cursor falls.  If the return is zero,
  836.    *   it's before the first character, if it falls off the end of
  837.    *   the string it's the length of the string + 1.
  838.    *
  839.    */
  840.   virtual PRInt32 GetPosition(const PRUnichar *aText,
  841.                               PRUint32 aLength,
  842.                               nsPoint aPt) = 0;
  843.  
  844.   /**
  845.    * Get the width for the specific range of a given string.
  846.    *
  847.    * This function is similar to other GetWidth functions, except that
  848.    * it gets the width for a part of the string instead of the entire
  849.    * string.  This is useful when you're interested in finding out the
  850.    * length of a chunk in the middle of the string.  Lots of languages
  851.    * require you to include surrounding information to accurately
  852.    * determine the length of a substring.
  853.    *
  854.    * @param aText Text on which to operate
  855.    * @param aLength Length of the text
  856.    * @param aStart Start index into the string
  857.    * @param aEnd End index into the string (inclusive)
  858.    * @param aWidth Returned with in app coordinates
  859.    *
  860.    */
  861.   NS_IMETHOD GetRangeWidth(const PRUnichar *aText,
  862.                            PRUint32 aLength,
  863.                            PRUint32 aStart,
  864.                            PRUint32 aEnd,
  865.                            PRUint32 &aWidth) = 0;
  866.  
  867.   /**
  868.    * Get the width for the specific range of a given string.
  869.    *
  870.    * Same as GetRangeWidth for PRUnichar, but takes a char * as the
  871.    * text argument.
  872.    *
  873.    */
  874.   NS_IMETHOD GetRangeWidth(const char *aText,
  875.                            PRUint32 aLength,
  876.                            PRUint32 aStart,
  877.                            PRUint32 aEnd,
  878.                            PRUint32 &aWidth) = 0;
  879.  
  880.   /**
  881.    * Render an encapsulated postscript object onto the current rendering
  882.    * surface.
  883.    *
  884.    * The EPS object must conform to the EPSF standard. See Adobe
  885.    * specification #5002, "Encapsulated PostScript File Format Specification"
  886.    * at <http://partners.adobe.com/asn/developer/pdfs/tn/5002.EPSF_Spec.pdf>.
  887.    * In particular, the EPS object must contain a BoundingBox comment.
  888.    *
  889.    * @param aRect  Rectangle in which to render the EPSF.
  890.    * @param aDataFile - plugin data stored in a file
  891.    * @return NS_OK for success, or a suitable error value.
  892.    *         NS_ERROR_NOT_IMPLEMENTED is returned if the rendering context
  893.    *         doesn't support rendering EPSF, 
  894.    */
  895.   NS_IMETHOD RenderEPS(const nsRect& aRect, FILE *aDataFile) = 0;
  896. };
  897.  
  898. //modifiers for text rendering
  899.  
  900. #define NS_DRAWSTRING_NORMAL            0x0
  901. #define NS_DRAWSTRING_UNDERLINE         0x1
  902. #define NS_DRAWSTRING_OVERLINE          0x2
  903. #define NS_DRAWSTRING_LINE_THROUGH      0x4
  904.  
  905. // Bit values for GetHints
  906.  
  907. /**
  908.  * This bit, when set, indicates that the underlying rendering system
  909.  * prefers 8 bit text rendering over PRUnichar text rendering. When this
  910.  * bit is <b>not</b> set the opposite is true: the system prefers PRUnichar
  911.  * rendering, not 8 bit rendering.
  912.  */
  913. #define NS_RENDERING_HINT_FAST_8BIT_TEXT   0x1
  914.  
  915. /**
  916.  * This bit, when set, indicates that the rendering is being done
  917.  * remotely.
  918.  */
  919. #define NS_RENDERING_HINT_REMOTE_RENDERING 0x2
  920.  
  921. /**
  922.  * This bit, when set, indicates that the system provides support for
  923.  * the reordering of bidirectional text
  924.  */
  925. #define NS_RENDERING_HINT_BIDI_REORDERING 0x4
  926.  
  927. /**
  928.  * This bit, when set, indicates that the system provides support for
  929.  * Arabic shaping
  930.  */
  931. #define NS_RENDERING_HINT_ARABIC_SHAPING 0x8
  932.  
  933. /**
  934.  * This bit, when set, indicates that gfx supports GetTextDimensions()
  935.  */
  936. #define NS_RENDERING_HINT_FAST_MEASURE 0x10
  937.  
  938. /**
  939.  * This bit, when set, indicates that the gfx supports describing
  940.  * cluster information in a string
  941.  */
  942. #define NS_RENDERING_HINT_TEXT_CLUSTERS 0x20
  943.  
  944. /**
  945.  * This bit, when set, indicates that gfx performs glyph reordering of complex
  946.  * text after applying character or word spacing, and so expects to be passed
  947.  * text in logical order. When this bit is not set, gfx must be passed text in
  948.  * visual order if characters and word spacing are to be applied.
  949.  */
  950. #define NS_RENDERING_HINT_REORDER_SPACED_TEXT 0x40
  951.  
  952. //flags for copy CopyOffScreenBits
  953.  
  954. //when performing the blit, use the region, if any,
  955. //that exists in the source drawingsurface as a
  956. //blit mask.
  957. #define NS_COPYBITS_USE_SOURCE_CLIP_REGION  0x0001
  958.  
  959. //transform the source offsets by the xform in the
  960. //rendering context
  961. #define NS_COPYBITS_XFORM_SOURCE_VALUES     0x0002
  962.  
  963. //transform the destination rect by the xform in the
  964. //rendering context
  965. #define NS_COPYBITS_XFORM_DEST_VALUES       0x0004
  966.  
  967. //this is basically a hack and is used by callers
  968. //who have selected an alternate drawing surface and
  969. //wish the copy to happen to that buffer rather than
  970. //the "front" buffer. i'm not proud of this. MMP
  971. //XXX: This is no longer needed by the XPCODE. It will
  972. //be removed once all of the platform specific nsRenderingContext's
  973. //stop using it.
  974. #define NS_COPYBITS_TO_BACK_BUFFER          0x0008
  975.  
  976. /* Struct used to represent the overall extent of a string
  977.    whose rendering may involve switching between different
  978.    fonts that have different metrics.
  979. */
  980. struct nsTextDimensions {
  981.   // max ascent amongst all the fonts needed to represent the string
  982.   nscoord ascent;
  983.  
  984.   // max descent amongst all the fonts needed to represent the string
  985.   nscoord descent;
  986.  
  987.   // width of the string
  988.   nscoord width;
  989.  
  990.  
  991.   nsTextDimensions()
  992.   {
  993.     Clear();
  994.   }
  995.  
  996.   /* Set all member data to zero */
  997.   void 
  998.   Clear() {
  999.     ascent = descent = width = 0;
  1000.   }
  1001.  
  1002.   /* Sum with another dimension */
  1003.   void 
  1004.   Combine(const nsTextDimensions& aOther) {
  1005.     if (ascent < aOther.ascent) ascent = aOther.ascent;
  1006.     if (descent < aOther.descent) descent = aOther.descent;   
  1007.     width += aOther.width;
  1008.   }
  1009. };
  1010.  
  1011. #ifdef MOZ_MATHML
  1012. /* Struct used for accurate measurements of a string in order
  1013.    to allow precise positioning when processing MathML.
  1014. */
  1015. struct nsBoundingMetrics {
  1016.  
  1017.   ///////////
  1018.   // Metrics that _exactly_ enclose the text:
  1019.  
  1020.   // The character coordinate system is the one used on X Windows:
  1021.   // 1. The origin is located at the intersection of the baseline
  1022.   //    with the left of the character's cell.
  1023.   // 2. All horizontal bearings are oriented from left to right.
  1024.   // 3. The ascent is oriented from bottom to top (being 0 at the orgin).
  1025.   // 4. The descent is oriented from top to bottom (being 0 at the origin).
  1026.  
  1027.   // Note that Win32/Mac/PostScript use a different convention for
  1028.   // the descent (all vertical measurements are oriented from bottom
  1029.   // to top on these palatforms). Make sure to flip the sign of the
  1030.   // descent on these platforms for cross-platform compatibility.
  1031.  
  1032.   // Any of the following member variables listed here can have 
  1033.   // positive or negative value.
  1034.  
  1035.   nscoord leftBearing;
  1036.        /* The horizontal distance from the origin of the drawing
  1037.           operation to the left-most part of the drawn string. */
  1038.  
  1039.   nscoord rightBearing;
  1040.        /* The horizontal distance from the origin of the drawing
  1041.           operation to the right-most part of the drawn string.
  1042.           The _exact_ width of the string is therefore:
  1043.           rightBearing - leftBearing */
  1044.   
  1045.   nscoord ascent;
  1046.        /* The vertical distance from the origin of the drawing 
  1047.           operation to the top-most part of the drawn string. */
  1048.  
  1049.   nscoord descent;
  1050.        /* The vertical distance from the origin of the drawing 
  1051.           operation to the bottom-most part of the drawn string.
  1052.           The _exact_ height of the string is therefore:
  1053.           ascent + descent */
  1054.  
  1055.   //////////
  1056.   // Metrics for placing other surrounding text:
  1057.  
  1058.   nscoord width;
  1059.        /* The horizontal distance from the origin of the drawing
  1060.           operation to the correct origin for drawing another string
  1061.           to follow the current one. Depending on the font, this
  1062.           could be greater than or less than the right bearing. */
  1063.  
  1064.   nsBoundingMetrics() {
  1065.     Clear();
  1066.   }
  1067.  
  1068.   //////////
  1069.   // Utility methods and operators:
  1070.  
  1071.   /* Set all member data to zero */
  1072.   void 
  1073.   Clear() {
  1074.     leftBearing = rightBearing = 0;
  1075.     ascent = descent = width = 0;
  1076.   }
  1077.  
  1078.   /* Append another bounding metrics */
  1079.   /* Notice that leftBearing is not set. The user must set leftBearing on 
  1080.      initialization and (repeatedly) use this operator to append 
  1081.      other bounding metrics on the right.
  1082.    */
  1083.   void 
  1084.   operator += (const nsBoundingMetrics& bm) {
  1085.     if (ascent < bm.ascent) ascent = bm.ascent;
  1086.     if (descent < bm.descent) descent = bm.descent;   
  1087.     rightBearing = width + bm.rightBearing;
  1088.     width += bm.width;
  1089.   }
  1090. };
  1091. #endif // MOZ_MATHML
  1092.  
  1093. #endif /* nsIRenderingContext_h___ */
  1094.